Removes a solid-colored background with a soft edge and spill suppression, and fills it with a color, an image, or — in a VideoComposition — the layer below, so a video can sit behind the screen.

// measured off the footage — works for any saturated screen hue
final key = await ChromaKey.autoDetect(clip, backgroundColor: Colors.black);

// or a video behind the screen
VideoRenderData(
  composition: VideoComposition(layers: [
    VideoLayer(clips: [VideoSegment(video: backdrop)]),
    VideoLayer(clips: [VideoSegment(video: clip)], chromaKey: const ChromaKey()),
  ]),
);

Settable on VideoRenderData, VideoLayer and VideoSegment, resolved per clip as segment → layer → global.

How it works

The whole key — matte alpha and despilled color — is a pure function of RGB. That is what lets Apple do it through a CIColorCube with varying, premultiplied alpha: no CIKernel, no Metal, neither of which this repo has today. Android needs a real shader, because SingleColorLut cannot produce alpha; ChromaKeyEffect is modelled on the existing VideoCompositionTransformation.

Both platforms run the same BT.601 chroma-distance formula, pinned by an identical golden table in the Kotlin and Swift unit tests — so a drift in either implementation fails a fast test instead of surfacing later as "the key looks different on iOS".

Why autoDetect

A constant key sits beside the recorded screen. The demo clip's screen is painted SMPTE green (0xFF00B140); the camera recorded 0xFF2A9D37 — a chroma distance of 0.12. That offset has to be paid for with a wider similarity, which is exactly the margin protecting the subject.

Same footage, roughly twice the headroom. Detection samples a border ring through the existing thumbnail pipeline, so it is pure Dart and touches no native code. ChromaKey.detect returns the raw measurement (color, spread, border coverage) for showing to the user, and throws ChromaKeyDetectionException when the border is not a clean screen.

greenScreen() / blueScreen() presets carry the measured values. Blue is not green with a different hue — it separates skin better (0.41–0.46 vs 0.38–0.42) but denim (0.19), blue eyes (0.20) and light blue shirts (0.21) all sit inside the green-tuned default, so the blue preset keys tighter and despills more gently.

Two pre-existing bugs fixed along the way

• VideoCompositionTransformation squared each composition layer's alpha. It blended against an already-transparent framebuffer (dst.a = a² + 0·(1−a)). A no-op while every layer was opaque; load-bearing once a keyed layer arrives with a soft edge. Confirmed against Media3's own DefaultCompositorGlProgram, which uses glBlendFuncSeparate and does the one real blend.
• EditorVideo.safeFilePath named its temp file from the millisecond alone, so sources resolved concurrently — as VideoRenderData.toAsyncMap does — could overwrite each other.

Not covered

• No time ranges on a key (unlike ColorFilter); split the clip instead.
• Ignored inside an overlap ClipTransition when the two clips carry different keys — the blend is pre-rendered from raw sources and is emitted unkeyed with a warning.
• No matte choke/erode, no light wrap.
• H.264/HEVC carry no alpha, so on the single-track videoSegments path a key without a background is flattened to black. There is a debug assert pointing at composition.

Verification

The example app gets its own Chroma Key page with a "measure the screen" button, a color/image/video background switch and sliders for all three parameters. The demo asset is a real studio green-screen clip, cropped to the screen area and downscaled to 330 KB.

Separately noted while building the test fixtures, not touched here: two renderStopMotion outputs do not concatenate (2s + 2s comes out as 2.03s on macOS). Unrelated to this change, but it looks like a real bug.